#LyX 2.0 created this file. For more info see http://www.lyx.org/ \lyxformat 413 \begin_document \begin_header \textclass article \use_default_options true \maintain_unincluded_children false \language english \language_package default \inputencoding auto \fontencoding global \font_roman default \font_sans default \font_typewriter default \font_default_family default \use_non_tex_fonts false \font_sc false \font_osf false \font_sf_scale 100 \font_tt_scale 100 \graphics default \default_output_format default \output_sync 0 \bibtex_command default \index_command default \paperfontsize default \spacing single \use_hyperref false \papersize default \use_geometry false \use_amsmath 1 \use_esint 1 \use_mhchem 1 \use_mathdots 1 \cite_engine basic \use_bibtopic false \use_indices false \paperorientation portrait \suppress_date false \use_refstyle 1 \index Index \shortcut idx \color #008000 \end_index \secnumdepth 3 \tocdepth 3 \paragraph_separation indent \paragraph_indentation default \quotes_language english \papercolumns 1 \papersides 1 \paperpagestyle default \tracking_changes false \output_changes false \html_math_output 0 \html_css_as_file 0 \html_be_strict false \end_header \begin_body \begin_layout Title Pontarius XMPP 0.1 Manual (Third Draft) \end_layout \begin_layout Author The Pontarius Project \end_layout \begin_layout Date The 6th of July, 2011 \end_layout \begin_layout Standard \begin_inset CommandInset toc LatexCommand tableofcontents \end_inset \end_layout \begin_layout Section Introduction \end_layout \begin_layout Standard Pontarius XMPP aims to be a convenient-to-use, powerful, correct, secure, and extendable XMPP client library for Haskell. It is written by Jon Kristensen and Mahdi Abdinejadi. Being licensed under the GNU Lesser General Public License, Pontarius XMPP is free and open source software. \end_layout \begin_layout Section Features and Implementation Specifics \end_layout \begin_layout Standard Pontarius XMPP 0.1 implements the client capabilities of the XMPP Core specificat ion (RFC 6120) \begin_inset Foot status open \begin_layout Plain Layout http://tools.ietf.org/html/rfc6120 \end_layout \end_inset . Below are the specifics of our implementation. \end_layout \begin_layout Itemize The client is always the initiating entity \end_layout \begin_layout Itemize A client-of-server connection is always exactly one TCP connection \end_layout \begin_layout Itemize TLS is supported for client-to-server confidentiality \end_layout \begin_layout Itemize Only the SCRAM authentication method is supported \end_layout \begin_layout Itemize ... \end_layout \begin_layout Standard Later versions will add supports for different XMPP extensions, such as RFC 6121 (XMPP IM), XEP-0004: Data Forms, and XEP-0077: In-Band Registration. \begin_inset Foot status open \begin_layout Plain Layout XMPP RFCs can be found at http://xmpp.org/xmpp-protocols/rfcs/, and the so-called XEPs at http://xmpp.org/xmpp-protocols/xmpp-extensions/. \end_layout \end_inset \end_layout \begin_layout Section Usage \end_layout \begin_layout Standard Working with Pontarius XMPP is mostly done asynchronously; Pontarius XMPP ``owns'' the XMPP thread, and calls different StateT s m a callback functions in the client. StateT is a monad transformer which allows the functions to be stateful (being able to access and modify the arbitrary client-defined state of type s) and to be executed on top of a MonadIO m monad (typically IO). \end_layout \begin_layout Subsection Creating the session \end_layout \begin_layout Standard Setting up an XMPP session is done through the (blocking) session function: \end_layout \begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout session :: (MonadIO m, ClientState s m) => s -> \end_layout \begin_layout Plain Layout [ClientHandler s m] -> (StateT s m ()) -> m () \end_layout \end_inset \end_layout \begin_layout Standard The first parameter (of type s) is an arbitrary state that is defined by the client. This is the initial state, and it will be passed to the stateful client callbacks. It will typically be modified by the client. \end_layout \begin_layout Standard The second parameter is the list of client handlers to deal with XMPP callbacks. The reason why we have a list is because we want to provide a ``layered'' system of XMPP event handlers. For example, XMPP client developers may want to have a dedicated handler to manage messages, implement a spam protection system, and so on. Messages are piped through these handlers one by one, and any handler may block the message from being sent to the next handler(s) above in the stack. \end_layout \begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout data MonadIO m => ClientHandler s m = ClientHandler { \end_layout \begin_layout Plain Layout messageReceived :: Maybe (Message -> \end_layout \begin_layout Plain Layout StateT s m Bool), presenceReceived :: Maybe \end_layout \begin_layout Plain Layout (Presence -> StateT s m Bool), iqReceived :: \end_layout \begin_layout Plain Layout Maybe (IQ -> StateT s m Bool), \end_layout \begin_layout Plain Layout sessionTerminated :: Maybe (TerminationReason -> \end_layout \begin_layout Plain Layout StateT s m ()) } \end_layout \end_inset \end_layout \begin_layout Standard ClientHandler is a record which specifies four callback functions. The first three deals with the three XMPP stanzas, and are called once an XMPP stanza is received. These functions take the stanza in question, and are stateful with the current client state. The boolean value returned signals whether or not the message should be blocked to clients further down the stack. For example, a XEP-0030: Service Discovery handler may choose to hide disco#inf o requests handlers above it in the stack. The last function is the callback that is used when the XMPP session is terminated. All callbacks are optional. \end_layout \begin_layout Standard The third argument to session is a callback function that will be called when the session has been initialized. \end_layout \begin_layout Standard Any function with access to the Session object can operate with the XMPP session, such as connecting the XMPP client or sending stanzas. More on this below. \end_layout \begin_layout Subsection Connecting the client \end_layout \begin_layout Standard Different clients connect to XMPP in different ways. Some secure the stream with TLS, and some authenticate with the server. Pontarius XMPP provides a flexible function to help out with this in a convenient way: \end_layout \begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout connect :: MonadIO m => Session s m -> HostName -> \end_layout \begin_layout Plain Layout PortNumber -> Maybe (Certificate, (Certificate -> \end_layout \begin_layout Plain Layout Bool)) -> Maybe (UserName, Password, Maybe \end_layout \begin_layout Plain Layout Resource) -> (ConnectResult -> StateT s m ()) -> \end_layout \begin_layout Plain Layout StateT s m () \end_layout \end_inset \end_layout \begin_layout Standard This function simply takes the host name and port number to connect to, an optional tuple of the certificate to use and a function evaluating certifica tes for TLS (if Nothing is provided, the connection will not be TLS secured), and another optional tuple with user name, password, and an optional resource for authentication (analogously, providing Nothing here causes Pontarius XMPP not to authenticate). The final paramter is a callback function providing the result of the connect action. \end_layout \begin_layout Standard For more fine-grained control of the connection, use the openStream, secureWithT LS, and authenticate functions. \end_layout \begin_layout Subsection Managing XMPP addresses \end_layout \begin_layout Standard There are four functions dealing with XMPP addresses (or JIDs, as they are also called): \end_layout \begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout fromString :: String -> Maybe Address \end_layout \begin_layout Plain Layout fromStrings :: Maybe String -> String -> \end_layout \begin_layout Plain Layout Maybe String -> Maybe Address \end_layout \begin_layout Plain Layout isBare :: Address -> Bool \end_layout \begin_layout Plain Layout isFull :: Address -> Bool \end_layout \end_inset \end_layout \begin_layout Standard These functions should be pretty self-explainatory to those who know the XMPP: Core standard. The fromString functions takes one to three strings and tries to construct an XMPP address. isBare and isFull checks whether or not the bare is full (has a resource value). \end_layout \begin_layout Subsection Sending stanzas \end_layout \begin_layout Standard Sending messages is done using this function: \end_layout \begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout sendMessage :: MonadIO m => Session s m -> Message -> \end_layout \begin_layout Plain Layout Maybe (Message -> StateT s m Bool) -> \end_layout \begin_layout Plain Layout Maybe (Timeout, StateT s m ()) -> \end_layout \begin_layout Plain Layout Maybe (StreamError -> StateT s m ()) -> \end_layout \begin_layout Plain Layout StateT s m () \end_layout \end_inset \end_layout \begin_layout Standard Like in section 3.2, the first parameter is the session object. The second is the message (check the Message record type in the API). The third parameter is an optional callback function to be executed if a reply to the message is received. The fourth parameter contains a Timeout (Integer) value, and a callback that Pontarius XMPP will call when a reply has not been received in the window of the timeout. The last parameter is an optional callback that is called if a stream error occurs. \end_layout \begin_layout Standard Presence and IQ stanzas are sent in a very similar way. \end_layout \begin_layout Standard Stanza IDs will be set for you if you leave them out. If, however, you want to know what ID you send, you can acquire a stanza ID by calling the getID function: \end_layout \begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout getID :: MonadIO m => Session s m -> StateT s m String \end_layout \end_inset \end_layout \begin_layout Subsection Concurrent usage \end_layout \begin_layout Standard Sometimes clients will want to perform XMPP actions from more than one thread, or in other words, they want to perform actions from code that is not a Pontarius XMPP callback. For these use cases, use injectAction: \end_layout \begin_layout Standard \begin_inset listings inline false status open \begin_layout Plain Layout injectAction :: MonadIO m => Session s m -> \end_layout \begin_layout Plain Layout Maybe (StateT s m Bool) -> StateT s m () -> \end_layout \begin_layout Plain Layout StateT s m () \end_layout \end_inset \end_layout \begin_layout Standard The second parameter is an optional predicate callback to be executed right before the third parameter callback is called. If it is provided and evaluates to False, then the action will not be called. Otherwise, the action will be called. \end_layout \begin_layout Subsection Example echo server \end_layout \begin_layout Standard We provide an example to further illustrate the Pontarius XMPP API and to make it easier for developers to get started with the library. The program illustrates how to connect, authenticate, set a presence, and echo all messages received. It only uses one client handler. The contents of this example may be used freely, as if it is in the public domain. You find it in the Examples directory of the Pontarius XMPP source code. \end_layout \end_body \end_document